Extend style guide "Use simple language" section #1624
Conversation
| - Abbreviations, such as Latin "e.g." or "i.e.," or symbols, such as the | ||
| ampersand ('&'), where English words will do, such as | ||
| "for example", "that is" and "and," respectively. |
There was a problem hiding this comment.
I don't agree with discouraging '&'. It's relatively common, and helps distinguish items in a list, e.g. "Tom & Jerry and Barbie & Ken have both featured in major animated works".
There was a problem hiding this comment.
| - Abbreviations, such as Latin "e.g." or "i.e.," or symbols, such as the | |
| ampersand ('&'), where English words will do, such as | |
| "for example", "that is" and "and," respectively. | |
| - Abbreviations, such as Latin "e.g." or "i.e." or symbols, such as the | |
| ampersand ("&"), where English words will do, such as | |
| "for example", "that is" and "and" respectively. |
I don't agree with discouraging '&'. It's relatively common
The same could be -- and was -- said for "e.g." and "i.e." too.
I wonder if this made more sense for printed media, since nowadays people can easily look those terms up and learn them instead.
| - Idioms, as they are often confusing to non-native speakers and | ||
| are difficult to translate. |
There was a problem hiding this comment.
I've said elsewhere, but part of the draw of Python is that it has historically been less 'clinical'/corporate/dry than other languages, and silly examples (Monty Python) & idioms in prose are part of that. I think there's a fine balance between avoiding overuse and confusion and a prohibition: I would be sad to see this type of thing go.
This reverts commit b1a65ba.
| To make the documentation more accessible and inclusive, the following should be | ||
| avoided: | ||
|
|
||
| - Esoteric phrasing. |
There was a problem hiding this comment.
Ironically "Esoteric phrasing" could arguably fit its own definition, even though these rules might not necessarily apply to the devguide itself. 🙃
| - Abbreviations, such as Latin "e.g." or "i.e.," or symbols, such as the | ||
| ampersand ('&'), where English words will do, such as | ||
| "for example", "that is" and "and," respectively. |
There was a problem hiding this comment.
| - Abbreviations, such as Latin "e.g." or "i.e.," or symbols, such as the | |
| ampersand ('&'), where English words will do, such as | |
| "for example", "that is" and "and," respectively. | |
| - Abbreviations, such as Latin "e.g." or "i.e." or symbols, such as the | |
| ampersand ("&"), where English words will do, such as | |
| "for example", "that is" and "and" respectively. |
I don't agree with discouraging '&'. It's relatively common
The same could be -- and was -- said for "e.g." and "i.e." too.
I wonder if this made more sense for printed media, since nowadays people can easily look those terms up and learn them instead.
The diff is quite short, and I think it will explain better than a comment here. A section on gender neutrality may also be a good addition, there is in fact already one in the translation style guide.